<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
  <meta name="generator" content=
  "HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org">

  <title>gbrowse_karyotype help</title>
</head>

<body>
  <h1><a class="mozTocH1" name=
  "mozTocId896364"></a>gbrowse_karyotype</h1><br>
  <hr style="width: 100%; height: 2px;">

  <h1><a class="mozTocH1" name="mozTocId42716"></a>TABLE OF
  CONTENTS</h1>

  <ul id="mozToc">
    <!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6-->

    <li><a href="#mozTocId896364">gbrowse_karyotype</a></li>

    <li><a href="#mozTocId42716">TABLE OF CONTENTS</a></li>

    <li><a href="#mozTocId965412">Using the URL query string
    interface</a></li>

    <li><a href="#mozTocId53094">URL structure</a></li>

    <li><a href="#mozTocId903004">Summary of CGI arguments</a></li>

    <li>
      <a href="#mozTocId555161">Detailed CGI Arguments</a>

      <ul>
        <li><a href="#mozTocId929932">Adding third-party
        annotations</a></li>

        <li>
          <a href="#mozTocId402313">The featuretext option</a>

          <ul>
            <li>
              <a href="#mozTocId60940">Configuration sections</a>

              <ul>
                <li><a href="#mozTocId774360">Colors</a></li>

                <li><a href="#mozTocId956973">Glyphs</a></li>
              </ul>
            </li>

            <li><a href="#mozTocId814311">The Reference
            Line</a></li>

            <li><a href="#mozTocId19187">The Data Lines</a></li>

            <li><a href="#mozTocId364025">The featuretext option
            can also contain GFF</a></li>

            <li><a href="#mozTocId586042">Comments</a></li>
          </ul>
        </li>
      </ul>
    </li>

    <li>
      <a href="#mozTocId221012">Browser customization and
      configuration</a>

      <ul>
        <li><a href="#mozTocId854590">The base configuration
        file</a></li>

        <li><a href="#mozTocId730868">The data source configuration
        file</a></li>

        <li><a href="#mozTocId66137">gbrowse_karyotype as an
        interactive browser</a></li>
      </ul>
    </li>

    <li>
      <a href="#mozTocId329627">How to obtain and use cytoband
      data</a>

      <ul>
        <li>
          <a href="#mozTocId384003">Format and graphical rendering
          of chromosome bands</a>

          <ul>
            <li><a href="#mozTocId609743">Stains and background
            colors</a></li>

            <li><a href="#mozTocId691394">Tips, stalks, and
            centromeres</a></li>
          </ul>
        </li>

        <li><a href="#mozTocId235550">Sample GFF data</a></li>

        <li><a href="#mozTocId323980">Sample Data Extraction
        script</a></li>

        <li>
          <a href="#mozTocId133625">Options for server-side storage
          of chromosome band data</a>

          <ul>
            <li><a href="#mozTocId231053">In a relational
            database</a></li>

            <li><a href="#mozTocId362510">As a flat file</a></li>
          </ul>
        </li>
      </ul>
    </li>

    <li>
      <a href="#mozTocId311487">Other usage examples:</a>

      <ul>
        <li>
          <a href="#mozTocId745944">Using non-standard cytoband
          features: Human gene density plot</a>

          <ul>
            <li><a href="#mozTocId749659">Sample GFF data</a></li>

            <li><a href="#mozTocId225713">Configuration
            file</a></li>

            <li><a href="#mozTocId271427">URL</a></li>
          </ul>
        </li>

        <li>
          <a href="#mozTocId764480">Loading chromosome band data
          remotely</a>

          <ul>
            <li><a href="#mozTocId360354">CGI arguments</a></li>

            <li><a href="#mozTocId499814">GET vs. POST
            method</a></li>
          </ul>
        </li>
      </ul>
    </li>

    <li><a href="#mozTocId244872">SEE ALSO:</a></li>

    <li><a href="#mozTocId812098">BUGS</a></li>

    <li><a href="#mozTocId27339">AUTHOR</a></li>
  </ul><br>
  <hr style="width: 100%; height: 2px;">

  <h1><a class="mozTocH2" name="mozTocId965412"></a>Using the URL
  query string interface</h1>Using gbrowse_karyotype to draw a
  karyotype in a web page is as simple as creating an &lt;img&gt;
  or &lt;iframe&gt; element that uses the URL for the CGI script as
  the <span style="font-style: italic;">src</span> attribute.<br>

  <p>For example, an &lt;img&gt; element like this:</p>
  <pre>
&lt;img src="/cgi-bin/gbrowse_karyotype?src=Homo_sapiens"&gt;
</pre>
  <pre>
<br>
Will generate this image:
</pre><br>
  <img alt="karyotype image" src=
  "/cgi-bin/gbrowse_karyotype?src=Homo_sapiens"><br>
  <br>
  <br>

  <p>gbrowse_karyotype can also be used to generate image-mapped
  HTML either on its own or as the contents of an &lt;iframe&gt;
  element.<br>
  For example (the URL parameters are described below):</p>
  <pre>
&lt;iframe height=300 width=150 frameborder=0 scrolling=no <br>
 src="/cgi-bin/gbrowse_karyoype?src=Homo_sapiens;e=1;c=1+2+3;h=250"&gt;<br>
&lt;/iframe&gt;
</pre><span style="font-style: italic;">yields the image
below.&nbsp; The chromosome bands now have mousover
labels:</span><br>
  <iframe src=
  "/cgi-bin/gbrowse_karyotype/Homo_sapiens?e=1;c=1+2+3;h=250"
  frameborder="0" height="300" scrolling="no" width=
  "150"></iframe><br>
  <br>

  <p>The script can also be used to superimpose external features
  onto the display.&nbsp; If we add the following argument to the
  above iframe example:<br></p>
  <pre>
  a=1+gene+gene1+50000000..5100000+bgcolor=red;a=1+gene+gene1+61000000..6300000+bgcolor=blue
</pre><iframe src=
"/cgi-bin/gbrowse_karyotype/Homo_sapiens?e=1;c=1+2+3;h=250;a=1+gene+gene1+20000..30000+bgcolor=red;a=1+gene+gene2+110000000..110010000+bgcolor=blue"
  frameborder="0" height="300" scrolling="no" width=
  "150"></iframe><br>

  <h1><a class="mozTocH2" name="mozTocId53094"></a><a name=
  "URL_str"></a>URL structure</h1><span style=
  "color: rgb(51, 51, 255);">http://mckay.cshl.edu/cgi-bin/</span><span style="color: rgb(51, 204, 0);">Homo_sapiens</span><span style="color: rgb(255, 0, 0);">?e=1;b=1;a=1+gene+gene1+2000..10000</span><br>

  <br>

  <ul>
    <li><span style="color: rgb(51, 51, 255);">base URL</span> --
    the location of the gbrowse_karyotype script</li>

    <li><span style="color: rgb(51, 204, 0);">data source</span> --
    the name of the optional data source.&nbsp; This can specified
    as part of the URL path (as shown) or as a CGI argument, eg
    "src=Homo_sapiens".</li>

    <li><span style="color: rgb(255, 0, 0);">CGI arguments</span>
    -- these are always '=' separated key value pairs.&nbsp; For
    aguments that require multiple parts (see below), the parts are
    separated by white-space*.<br></li>
  </ul>*Note: white-space and other non-word characters must be
  <a href="#escape">URL-escaped</a> if passed as CGI arguments
  using the GET method.&nbsp; This is explained in more detail
  <a href="#escape">below</a>.<br>

  <h1><a class="mozTocH2" name="mozTocId903004"></a><a name=
  "CGI"></a>Summary of CGI arguments</h1>

  <p>The script recognizes the following CGI arguments.&nbsp;
  Argument pairs must be separated by semicolons or by
  ampersands.&nbsp;<br>
  Most options have shorter aliases that can be used to reduce URL
  lengths.&nbsp; Default values for each of the options&nbsp; in
  bold<br>
  face can also be specified in the configuration file for the data
  source, if one is used.<br></p>

  <table style="background-color: rgb(255, 255, 204);" border="1">
    <tbody>
      <tr>
        <th>Argument</th>

        <th>Alias</th>

        <th>Description</th>
      </tr>

      <tr>
        <td><a href="#type">type</a></td>

        <td>t</td>

        <td>built-in tracks to include in image</td>
      </tr>

      <tr>
        <td><a href="#rows"><span style=
        "font-weight: bold;">rows</span></a><br></td>

        <td>r<br></td>

        <td>number of rows of chromosomes to draw<br></td>
      </tr>

      <tr>
        <td><a href="#chromosome"><span style=
        "font-weight: bold;">chromosome</span></a><br></td>

        <td>c<br></td>

        <td>which chromosome(s) to draw<br></td>
      </tr>

      <tr>
        <td><a href="#">style</a></td>

        <td>s</td>

        <td>style information for added features</td>
      </tr>

      <tr>
        <td><a href="#add">add</a></td>

        <td>a</td>

        <td>added feature(s) to superimpose on the image</td>
      </tr>

      <tr>
        <td><a href="#embed">embed</a></td>

        <td>e<br></td>

        <td>generate full HTML for image and imagemap for use in an
        embedded frame</td>
      </tr>

      <tr>
        <td style="font-weight: bold;"><a href=
        "#transparent">transparent</a></td>

        <td>tr<br></td>

        <td>make the image background color transparent</td>
      </tr>

      <tr>
        <td><a href="#cwidth"><span style=
        "font-weight: bold;">cwidth</span></a><br></td>

        <td>w<br></td>

        <td>chromsome width<br></td>
      </tr>

      <tr>
        <td><a href="#cheight"><span style=
        "font-weight: bold;">cheight</span></a><br></td>

        <td>h<br></td>

        <td>maximum chromosome height<br></td>
      </tr>

      <tr>
        <td><a href="#bandlabels"><span style=
        "font-weight: bold;">bandlabels</span></a><br></td>

        <td>b<br></td>

        <td>label chromosome bands<br></td>
      </tr>

      <tr>
        <td style="vertical-align: top;"><a href=
        "#band"><span style=
        "font-weight: bold;">band</span></a><br></td>

        <td style="vertical-align: top;">ba<br></td>

        <td style="vertical-align: top;">the type of feature to be
        used as chromosome bands or centromeres<br></td>
      </tr>

      <tr>
        <td><a href="#list">list</a></td>

        <td>&nbsp;l</td>

        <td>get certain types of configuration information</td>
      </tr>

      <tr>
        <td><a href="#source">source</a></td>

        <td>&nbsp;src</td>

        <td>database name</td>
      </tr>

      <tr>
        <td style="vertical-align: top;"><a style=
        "font-weight: bold;" href="#useform">useform</a><br></td>

        <td style="vertical-align: top;">f<br></td>

        <td style="vertical-align: top;">print a data entry form if
        there are no other CGI parameters.&nbsp;<br></td>
      </tr>

      <tr>
        <td style="vertical-align: top;"><a href=
        "featuretext">featuretext</a><br></td>

        <td style="vertical-align: top;">ft<br></td>

        <td style="vertical-align: top;">enter third-party
        annotations as Bio::Graphics::FeatureFile-style
        text.<br></td>
      </tr>
    </tbody>
  </table>

  <p><br></p>

  <h1><a class="mozTocH3" name="mozTocId555161"></a>Detailed CGI
  Arguments</h1><span style="font-weight: bold;"><a name=
  "type"></a>type</span> (Alias: <span style=
  "font-weight: bold;">t</span>)

  <dl>
    <dd>
      This argument applies only to configured data sources on the
      web server (see <a href="#configuration">configuration</a>
      below).&nbsp; The 'type' option lists the feature types to
      display with the karyotype. The value of this argument is a
      list of track names separated by spaces ("+" characters when
      URL-escaped). For example:<br>
      <pre>
 &lt;img src="/cgi-bin/gbrowse_karyotype?src=rat;type=gene+allele"&gt;
</pre><br>
      Multiple <i>type=</i> arguments will be combined to form a
      single space-delimited list. The alias "t" can be used to
      shorten the length of the URL.

      <p>If the track name has a space in it, put quotes around the
      name:</p>
      <pre>
 type="microbe tRNA"+NG+WABA+CG+ESTB
</pre>Available track names can be listed by calling the
gbrowse_karyotype script with the option "list=types",
      <pre>
 /cgi-bin/gbrowse_karyotype/sourcename?list=types or /cgi-bin/gbrowse_karyotype?src=sourcename;list=types 
</pre>
    </dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "chromosome"></a>chromome</span> (Alias: <span style=
    "font-weight: bold;">c</span>)</dt>

    <dd>
      Number and order of chromosomes to draw.&nbsp; The default is
      to draw all chromosomes.&nbsp; Multiple chromosomes can be
      specified in a space-delimited list ("+" characters when
      URL-escaped).&nbsp; For example c=1+2+3+4 will draw
      chromosomes 1-4.&nbsp; If drawing a genome for which there is
      no data source or configuration file on the server, specify
      the length of each chromosome in addition to the
      name.&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br>

      <pre>
      c=1:250000000+2:200000000+3:180000000
</pre>
    </dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "rows"></a>rows</span> (Alias: <span style=
    "font-weight: bold;">r</span>)</dt>

    <dd>The number or rows to arrange the chromosomes in.&nbsp; The
    default behavior is to automatically adjust the number of rows
    to keep the image less than or equal to 1024 pixels in
    width.</dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "cwidth"></a>cwidth</span> (Alias: <span style=
    "font-weight: bold;">w</span>) Width of the chromosomes, in
    pixels. &nbsp; The default value is 20px.</dt>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "cheight"></a>cheight</span> (Alias: <span style=
    "font-weight: bold;">h</span>)</dt>

    <dd>Height of the largest chromosome, in pixels.&nbsp; This
    option affects the overall image height.&nbsp; Chromosome
    lengths are scaled by their size in bp.&nbsp; The default is
    500 px.</dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "arcradius"></a>arcradius</span> (Alias: <span style=
    "font-weight: bold;">ar</span>)</dt>

    <dd>The radius of the round part of the telomere in
    pixels.&nbsp; The default value is calculated as 1/100 of the
    maximum chromosome length.</dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "transparent"></a>transparent</span> (Alias: <span style=
    "font-weight: bold;">tr</span>)</dt>

    <dd>The "transparent" option is used to determine whether the
    karyotype image uses either a white or transparent background.
    Defining the "transparent" parameter will cause the image to
    appear to have whatever background color is used by the parent
    web page.</dd>

    <dd><br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name="style"></a>
    style</span> (Alias: a)</dt>

    <dd>
      The style argument can be used to control the default
      rendering of features added via the "add" option.<br>
      It is a flattened version of the style configuration sections
      described in <a href="/cgi-bin/gbrowse?help=annotation">this
      document</a><br>
      For example, if you have added a "Blast Hit" annotation, then
      you can tell the renderer to use a red bar for this glyph in
      this way:
      <pre>
 style="Blast Hit"+glyph=generic+bgcolor=red
</pre><br>
      <span style="font-weight: bold;">Note:</span> The 'style'
      parameter controls how all features of a specified type are
      rendered. The general style directives can be overriden for
      individual features via the 'add' option described below.
    </dd>

    <dd><span style="font-weight: bold;">Note2:</span> For large
    numbers of added features or complex configuration, see the
    <a href="#featuretext">featuretext</a> option.</dd>

    <dd>
      <h2><a class="mozTocH2" name="mozTocId929932"></a>Adding
      third-party annotations</h2><br>
    </dd>

    <dt><span style="font-weight: bold;"><a name=
    "add"></a>add</span> (Alias: a)</dt>

    <dd>
      This option is used to add one or more additional features to
      the karyotype, for example, genes, blast hits, etc. Features
      are specified as space ("+") delimited lists in the following
      format:<br>
      <br>
      <pre>
    <big>add=<span style=
"color: rgb(51, 102, 255);">chr2</span>+<span style=
"color: rgb(51, 204, 0);">Type</span>+<span style=
"color: rgb(255, 0, 0);">Name</span>+<span style=
"color: rgb(153, 51, 153);">start..end,start2..end2</span>+<span style="color: rgb(51, 0, 51);">bgcolor=green+glyph=dot+desc='my+favorite+gene'</span></big>
</pre>

      <ul>
        <li><span style=
        "color: rgb(51, 102, 255); font-weight: bold;">"ref"</span>
        is the name of the reference sequence</li>

        <li><span style=
        "color: rgb(51, 204, 0); font-weight: bold;">"type"</span>
        link the feature to a style definition (see "style" below),
        if used</li>

        <li><span style=
        "color: rgb(255, 0, 0); font-weight: bold;">"name"</span>
        is the unique feature name or identifier. It will be used a
        a mousover label if the 'embed' option is selected and
        there is no description. Names that contain white space
        must be quoted, for example "BLAST hit".</li>

        <li><span style=
        "color: rgb(204, 51, 204); font-weight: bold;">"coordinates"</span>
        is a range in the format start..end. Multiple ranges can be
        used as a comma-separated list (eg:
        start..end,start2..end2,start3..end3). Negative strand
        features can be specified by inverting the start and end
        coordinates.</li>

        <li>Other fields can optionally be appended after the
        coordinates to control how the feature is drawn.</li>
      </ul><br>
      Free-form text will be interpreted as a description, for
      example:<br>
      <pre>
 add=I+"curated+gene"+act-2+23897..28799+<span style=
"font-weight: bold;">"C.+elegans+actin+gene"</span>
</pre>"key=value" pairs will be added to the feature's attributes.
Certain reserved keywords will override any default style for that
feature type.
    </dd>

    <dd>
      &nbsp;<br>

      <table cell-padding="5" style=
      "background-color: rgb(255, 255, 204);" border="1">
        <tbody>
          <tr>
            <th colspan="2">reserved keywords<br></th>
          </tr>

          <tr>
            <th align="left">glyph</th>

            <td>the type of glyph used to represent the feature
            (eg: 'dot', 'diamond', 'triangle')</td>
          </tr>

          <tr>
            <th align="left">fgcolor</th>

            <td>glyph foreground (outline) color</td>
          </tr>

          <tr>
            <th align="left">bgcolor</th>

            <td>glyph background (fill) color</td>
          </tr>

          <tr>
            <th align="left">orient</th>

            <td>cardinal direction that glyph points in; N, S, E,
            W</td>
          </tr>

          <tr>
            <th align="left">url (alias 'link')</th>

            <td>URL destination if the feature is clicked (see Note
            below)</td>
          </tr>

          <tr>
            <th align="left">desc (alias 'description')</th>

            <td>feature description. This will be used as a
            mousover label.</td>
          </tr>
        </tbody>
      </table>

      <p><span style="font-weight: bold;"><a name="escape"></a>
      Note:</span> URLs that contain special characters such as
      '&amp;', ';', '~', etc must be URL escaped in order to be
      parsed properly. Allowed special characters and their ASCII
      escape codes are listed below. URLs containing special
      characters that are not on this list are not allowed.</p>
    </dd>

    <dd>
      <table border="1">
        <tbody>
          <tr>
            <th style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            character</th>

            <th style="background-color: rgb(204, 204, 204);">
            escape code</th>

            <th style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            character</th>

            <th style="background-color: rgb(204, 204, 204);">
            escape code</th>
          </tr>

          <tr>
            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            #</td>

            <td style="background-color: rgb(204, 204, 204);">
            %23</td>

            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            ~</td>

            <td style="background-color: rgb(204, 204, 204);">
            %7E</td>
          </tr>

          <tr>
            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            /</td>

            <td style="background-color: rgb(204, 204, 204);">
            %2F</td>

            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            ?</td>

            <td style="background-color: rgb(204, 204, 204);">
            %3F</td>
          </tr>

          <tr>
            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            :</td>

            <td style="background-color: rgb(204, 204, 204);">
            %3A</td>

            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            @</td>

            <td style="background-color: rgb(204, 204, 204);">
            %40</td>
          </tr>

          <tr>
            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            =</td>

            <td style="background-color: rgb(204, 204, 204);">
            %3D</td>

            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            &amp;</td>

            <td style="background-color: rgb(204, 204, 204);">
            %26</td>
          </tr>

          <tr>
            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            ;</td>

            <td style="background-color: rgb(204, 204, 204);">
            %3B</td>

            <td style=
            "background-color: rgb(255, 255, 204); text-align: center; font-weight: bold;">
            <br></td>

            <td style="background-color: rgb(204, 204, 204);">
            <br></td>
          </tr>

          <tr>
            <td></td>
          </tr>
        </tbody>
      </table>
    </dd>

    <dt><span style="font-weight: bold;"><a name=
    "list"></a>list</span> (Alias <span style=
    "font-weight: bold;">l</span>)</dt>

    <dd>
      If this argument is present, it will cause the script to dump
      out various types of information in plain text form.
      Currently the two values for this argument are
      <i>sources</i>, to dump out the list of data sources, and
      <i>types</i>, to dump out the list of configured types. For
      <i>list=sources</i>, the script will return a simple text
      list of the data source names. For <i>list=types</i>, the
      script will return a three-column tab-delimited list giving
      the track names and feature types corresponding to the
      currently-selected data source. The format is as follows:
      <pre>
 Mnemonic &lt;tab&gt; Full description of feature &lt;tab&gt; [default]
</pre>The third column contains the word "default" if the track
will be shown by default when no <i>type</i> argument is
provided.<br>
    </dd>

    <dd><br></dd>

    <dt><span style="font-weight: bold;"><a name="source"></a>
    source</span> (Alias <span style=
    "font-weight: bold;">src</span>)</dt>

    <dd>This argument specifies the database for the images. The
    list of sources can be found using <i>list=sources</i>.<br>
    <br></dd>

    <dt><span style="font-weight: bold;"><a name=
    "embed"></a>embed</span> (Alias: <span style=
    "font-weight: bold;">e</span>)</dt>

    <dd>
      Generate image and a corresponding HTML imagemap in a form
      suitable for embedding into a frame.&nbsp;<br>
      The default behavior for gbrowse_karyotype is to output
      binary image data. To embed an image in your web page with
      maousover effects, etc, use the embed=1 options and call the
      script via an &lt;iframe&gt; element. For example, the
      clickable image below is generated via an iframe element with
      this format:
      <pre>
&lt;iframe src="/cgi-bin/gbrowse_karyotype?c=1+2+3;h=350;src=mouse;e=1;a=2+gene+gene1+1000000..1010000+bgcolor=red+url=http://www.google.com" width="150" height="350"&gt;&lt;/iframe&gt;<br>
</pre>
    </dd>

    <dd>
      <p style="font-weight: bold;">Mouseover or click the
      triangle</p><iframe style="border: medium none ;" src=
      "/cgi-bin/gbrowse_karyotype?c=1+2+3;h=300;src=mouse;e=1;a=2+gene+gene1+10000000..10001000+bgcolor=red+url=http://www.google.com"
      height="350" scrolling="no" width="200"></iframe><br>
    </dd>
  </dl><br>

  <dl>
    <dt><span style="font-weight: bold;"><a name="useform"></a>
    useform</span> (Alias <span style=
    "font-weight: bold;">f</span>)</dt>

    <dd>If gbrowse_karyotype is being used as an interactive
    browser, define this option either as a CGI parameter or in the
    configuration file.&nbsp; If this option is set in the
    configuration file, the form will be printed when the script is
    called with no CGI parameters.&nbsp; If used as a CGI
    parameter, the form will be printed if there are no other CGI
    parameters.</dd>
  </dl>

  <h2><a class="mozTocH2" name="mozTocId402313"></a>The featuretext
  option</h2><br>

  <dl>
    <dt><span style="font-weight: bold;"><a name=
    "featuretext"></a>featuretext</span> (Alias <span style=
    "font-weight: bold;">ft</span>)</dt>

    <dt style="margin-left: 40px;">To submit large numbers of
    features or more complex annotation data, it may be preferable
    to use this option and the POST method rather than the 'add'
    and 'style' methods.&nbsp; The format of the text, which would
    be placed within a &lt;textarea&gt; element, follows the&nbsp;
    <a href=
    "http://doc.bioperl.org/releases/bioperl-current/bioperl-live/Bio/Graphics/FeatureFile.html">
    Bio::Graphics::FeatureFile</a> format, an example of which is
    shown below:</dt>

    <dd><br></dd>
  </dl>

    <pre style="background-color: gainsboro; width: 800px;">
## Default display options for gene ##
<span style="color: rgb(255, 0, 0);">[gene]</span>
<span style=
"color: rgb(255, 0, 0);">glyph   = triangle</span>
<span style="color: rgb(255, 0, 0);">bgcolor = red</span>
<span style="color: rgb(255, 0, 0);">fgcolor = red</span>
<span style="color: rgb(255, 0, 0);">height  = 7</span>
<span style="color: rgb(255, 0, 0);">bump    = 1</span>

<span style="color: rgb(255, 0, 0);">[mutation]</span>
<span style=
"color: rgb(255, 0, 0);">glyph   = lightning</span>
<span style=
"color: rgb(255, 0, 0);">bgcolor = yellow</span>
<span style=
"color: rgb(255, 0, 0);">fgcolor = black</span>
<span style="color: rgb(255, 0, 0);">height  = 15</span>

# chromosome 1
<span style="color: rgb(51, 102, 255);">reference=1</span>
<span style=
"color: rgb(51, 204, 0);">gene gene1 20000001..20006000 "Carbonic Anhydrase gene" </span>
<span style=
"color: rgb(51, 204, 0);">gene gene2 20066001..20069000 "ADH gene"</span>
<span style=
"color: rgb(51, 204, 0);">gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene"</span>

# chromosome 5
<span style="color: rgb(51, 102, 255);">reference=5</span>
<span style=
"color: rgb(51, 204, 0);">gene gene4 20000001..20006000 bgcolor=white</span>
<span style=
"color: rgb(51, 204, 0);">gene gene5 30006001..30009000</span>
<span style=
"color: rgb(51, 204, 0);">gene gene6 80000001..80006000</span>
<span style=
"color: rgb(51, 204, 0);">mutation allele2 30006001..30009000 "cosmic radiation damage"</span>
</pre>
  
  The components of the annotation/config text
  (<span style="color: rgb(255, 0, 0);">configuration
  sections</span>, <span style="color: rgb(51, 51, 255);">reference
  lines</span> and <span style="color: rgb(0, 153, 0);">data
  lines</span>) are discussed in detail below:<br>
  <br>
  <br>

  <h3><a class="mozTocH4" name="mozTocId60940"></a><a name=
  "annot_config"></a><span style=
  "color: rgb(255, 0, 0);">Configuration sections<br></span></h3>

  <p>The appearance of third-party annotations can be controlled by
  including one or more configuration stanzas in the annotation
  file.</p>

  <p>Here is an example configuration section. It can appear at the
  top of the file, at the bottom, or interspersed among data
  sections:</p>

  <blockquote>
    <pre>
[gene]<br>
glyph   = triangle<br>
orient  = E<br>
bgcolor = red<br>
fgcolor = red<br>
height  = 7<br>
bump    = 1<br>
</pre>
  </blockquote>

  <p>The configuration section is divided into a set of sections,
  each one labeled with a [section title]. The [general] section
  specifies global options for the entire image. Other sections
  apply to particular feature types.<br></p>

  <p>Inside each section is a series of <i>name</i>=<i>value</i>
  pairs, where the name is the name of an option to set. You can
  put whitespace around the = sign to make it more readable, or
  even use a colon (:) instead if you prefer. The following option
  names are recognized:</p>

  <table style="background-color: rgb(255, 255, 204);" border="1">
    <tbody>
      <tr>
        <th>Option</th>

        <th>Value</th>

        <th>Example</th>
      </tr>

      <tr>
        <th>bgcolor</th>

        <td>Background color of each element</td>

        <td>blue</td>
      </tr>

      <tr>
        <th>bump</th>

        <td>Prevent features from colliding (0=no, 1=yes; default
        1)</td>

        <td>1</td>
      </tr>

      <tr>
        <th>fgcolor</th>

        <td>Foreground color of each element</td>

        <td>yellow</td>
      </tr>

      <tr>
        <th>glyph</th>

        <td>Style of each graphical element (see list below)</td>

        <td>triangle</td>
      </tr>

      <tr>
        <th>width</th>

        <td>Width of each graphical element (pixels)</td>

        <td>10</td>
      </tr>

      <tr>
        <th>linewidth</th>

        <td>Width of lines (pixels)</td>

        <td>1</td>
      </tr>

      <tr>
        <th>orient</th>

        <td>Direction in which triangle and lightning glyphs point
        (N, S, E, W; default E)</td>

        <td>E<br></td>
      </tr>

      <tr>
        <th>point</th>

        <td>Place an unscaled glyph in the center of the range.
        (0=no, 1=yes; default 1)</td>

        <td>1</td>
      </tr>
    </tbody>
  </table>

  <p>The bump option is the most important option for controlling
  the look of the image. If set to false (the number 0), then the
  features are allowed to overlap. If set to true (the number 1),
  then the features will movehorizontally to avoid colliding. If
  not specified, bump is turned on if the number of any given type
  of sequence feature is greater than 50.</p>

  <p>Remote annotation files do not support callbacks (code
  references) as values in the attribute:value pairs.</p>

  <h4><a class="mozTocH5" name="mozTocId774360"></a><a name=
  "colors"></a>Colors</h4>Colors are English-language color names
  or Web-style #RRGGBB colors (see any book on HTML for an
  explanation). The following colors are recognized:

  <table style="background-color: rgb(255, 255, 204);" border="1">
    <tbody>
      <tr>
        <td>white</td>

        <td>coral</td>

        <td>darkslateblue</td>

        <td>green</td>

        <td>lightpink</td>

        <td>mediumslateblue</td>

        <td>paleturquoise</td>

        <td>sienna</td>
      </tr>

      <tr>
        <td>black</td>

        <td>cornflowerblue</td>

        <td>darkslategray</td>

        <td>greenyellow</td>

        <td>lightsalmon</td>

        <td>mediumspringgreen</td>

        <td>palevioletred</td>

        <td>silver</td>
      </tr>

      <tr>
        <td>aliceblue</td>

        <td>cornsilk</td>

        <td>darkturquoise</td>

        <td>honeydew</td>

        <td>lightseagreen</td>

        <td>mediumturquoise</td>

        <td>papayawhip</td>

        <td>skyblue</td>
      </tr>

      <tr>
        <td>antiquewhite</td>

        <td>crimson</td>

        <td>darkviolet</td>

        <td>hotpink</td>

        <td>lightskyblue</td>

        <td>mediumvioletred</td>

        <td>peachpuff</td>

        <td>slateblue</td>
      </tr>

      <tr>
        <td>aqua</td>

        <td>cyan</td>

        <td>deeppink</td>

        <td>indianred</td>

        <td>lightslategray</td>

        <td>midnightblue</td>

        <td>peru</td>

        <td>slategray</td>
      </tr>

      <tr>
        <td>aquamarine</td>

        <td>darkblue</td>

        <td>deepskyblue</td>

        <td>indigo</td>

        <td>lightsteelblue</td>

        <td>mintcream</td>

        <td>pink</td>

        <td>snow</td>
      </tr>

      <tr>
        <td>azure</td>

        <td>darkcyan</td>

        <td>dimgray</td>

        <td>ivory</td>

        <td>lightyellow</td>

        <td>mistyrose</td>

        <td>plum</td>

        <td>springgreen</td>
      </tr>

      <tr>
        <td>beige</td>

        <td>darkgoldenrod</td>

        <td>dodgerblue</td>

        <td>khaki</td>

        <td>lime</td>

        <td>moccasin</td>

        <td>powderblue</td>

        <td>steelblue</td>
      </tr>

      <tr>
        <td>bisque</td>

        <td>darkgray</td>

        <td>firebrick</td>

        <td>lavender</td>

        <td>limegreen</td>

        <td>navajowhite</td>

        <td>purple</td>

        <td>tan</td>
      </tr>

      <tr>
        <td>blanchedalmond</td>

        <td>darkgreen</td>

        <td>floralwhite</td>

        <td>lavenderblush</td>

        <td>linen</td>

        <td>navy</td>

        <td>red</td>

        <td>teal</td>
      </tr>

      <tr>
        <td>blue</td>

        <td>darkkhaki</td>

        <td>forestgreen</td>

        <td>lawngreen</td>

        <td>magenta</td>

        <td>oldlace</td>

        <td>rosybrown</td>

        <td>thistle</td>
      </tr>

      <tr>
        <td>blueviolet</td>

        <td>darkmagenta</td>

        <td>fuchsia</td>

        <td>lemonchiffon</td>

        <td>maroon</td>

        <td>olive</td>

        <td>royalblue</td>

        <td>tomato</td>
      </tr>

      <tr>
        <td>brown</td>

        <td>darkolivegreen</td>

        <td>gainsboro</td>

        <td>lightblue</td>

        <td>mediumaquamarine</td>

        <td>olivedrab</td>

        <td>saddlebrown</td>

        <td>turquoise</td>
      </tr>

      <tr>
        <td>burlywood</td>

        <td>darkorange</td>

        <td>ghostwhite</td>

        <td>lightcoral</td>

        <td>mediumblue</td>

        <td>orange</td>

        <td>salmon</td>

        <td>violet</td>
      </tr>

      <tr>
        <td>cadetblue</td>

        <td>darkorchid</td>

        <td>gold</td>

        <td>lightcyan</td>

        <td>mediumorchid</td>

        <td>orangered</td>

        <td>sandybrown</td>

        <td>wheat</td>
      </tr>

      <tr>
        <td>chartreuse</td>

        <td>darkred</td>

        <td>goldenrod</td>

        <td>lightgoldenrodyellow</td>

        <td>mediumpurple</td>

        <td>orchid</td>

        <td>seagreen</td>

        <td>whitesmoke</td>
      </tr>

      <tr>
        <td>chocolate</td>

        <td>darksalmon</td>

        <td>gray</td>

        <td>lightgreen</td>

        <td>mediumseagreen</td>

        <td>palegoldenrod</td>

        <td>seashell</td>

        <td>yellow</td>
      </tr>

      <tr>
        <td>coral</td>

        <td>darkseagreen</td>

        <td>green</td>

        <td>lightgrey</td>

        <td>mediumslateblue</td>

        <td>palegreen</td>

        <td>sienna</td>

        <td>yellowgreen</td>
      </tr>
    </tbody>
  </table>

  <h4><a class="mozTocH5" name="mozTocId956973"></a><a name=
  "glyphs"></a>Glyphs</h4>The <span>option controls how the
  features are rendered. There are dozens of glyphs available but
  not all are suitable for drawing features on a chromosome
  scale.&nbsp;&nbsp;&nbsp; A comprehensive list of available glyphs
  can be found on the <a href=
  "http://www.bioperl.org/wiki/Special:Search?search=glyph&amp;go=Go">
  bioperl website.</a>&nbsp; The following glyphs are recommended
  for best results:<br>
  <br></span>

  <table style="background-color: rgb(255, 255, 204);" border="1">
    <tbody>
      <tr>
        <th>Name</th>

        <th>Descripton</th>
      </tr>

      <tr>
        <th>triangle</th>

        <td>A triangle; use the 'orient' option (N,S,E or W) to
        control where it points.</td>
      </tr>

      <tr>
        <th>dot</th>

        <td>A small circle.</td>
      </tr>

      <tr>
        <th>diamond</th>

        <td>A diamond shape.</td>
      </tr>

      <tr>
        <th>lightning</th>

        <td>For those features who do not take themselves too
        seriously.<br></td>
      </tr>
    </tbody>
  </table><br>

  <h3><a class="mozTocH4" name="mozTocId814311"></a>The Reference
  Line</h3>The annotation file must have at least one reference =
  <i>landmark name</i> line. This line tells the browser what
  coordinate system you are using.&nbsp; This would typically be a
  chromosome name.&nbsp; The word "reference" must be all
  lower-case. There may or may not be whitespace before and after
  the "=" sign.

  <blockquote>
    <pre>
reference = 1
</pre>
  </blockquote>

  <p>You may have several reference lines in the file. Each
  reference landmark will apply to all data lines located beneath
  it until the next reference line occurs.</p>

  <h3><a class="mozTocH4" name="mozTocId19187"></a>The Data
  Lines</h3>The format of the data lines is analogous to that of
  the '<a href="#add">add</a>' option, except that the reference
  seuquence is specified only once per group and <a href=
  "#escape">URL-escaping</a> special characters is not
  required.&nbsp; Each annotation occupies one or more lines. It
  contains three to four columns, delimited by tabs or spaces.

  <p>Column 1, the feature type<br>
  The first column is the feature type. Any description is valid,
  but a short word, like "knockout" is better than a long one, like
  "Transposon-mediated knockout". Later on you can provide a long
  descriptive name in the formatting key if you desire. If the
  feature type contains white space, you must surround it by double
  or single quotes.</p>

  <p>Column 2, the feature name<br>
  This is the name of the feature. The name will be used as a
  mousover label unless there is a comment (see below).&nbsp; If
  the name contains white space, you must surround it by white
  space. Use empty quotes ("") if there is no name to display.</p>

  <p>Column 3, the feature position<br>
  The third column contains one or more ranges occupied by the
  feature. A range has a start and a stop, and is expressed either
  as "start..stop" or "start-stop". Use whichever form you prefer.
  You can express a feature that occupies a discontinuous set of
  ranges, such as an mRNA aligned to the genome, by providing a
  list of ranges separated by commas. Example: <span style=
  "font-family: monospace;"><br>
  &nbsp;</span><br>
  &nbsp;1..10,49..80,110..200</p>There should be no spaces before
  or after the commas. If there are, enclose the entire range in
  quotes.&nbsp; All ranges uses the coordinate system of the most
  recently declared reference landmark.

  <p>Column 4, Description [optional]<br>
  This is the description column.&nbsp; If a description exists, it
  will be used as a mouseover label for the feature, taking
  precedence over the feature name from column 2.&nbsp;
  Descriptions that contain whitespace should be wrapped in
  quotes.&nbsp; The description column can also be used to specify
  <i>attribute=value</i> information to override track display
  options for an individual feature.&nbsp; For example, if the
  features in a track are normally displayed as triangles, adding
  glyph=diamond to column 4 will draw a diamond in place of a
  triangle for just this one feature.&nbsp; Multiple
  attribute=value pairs should be delimited with semicolons.&nbsp;
  attribute=value pairs and text descriptions can be mixed by
  prepending a "decription=" to the text.&nbsp; For
  example:<br></p>
  <pre>
 gene gene1 10001..16000 bgcolor=white;glyph=dot;description="a very special gene"   <br>
<br>
<br>
</pre>

  <h3><a class="mozTocH3" name="mozTocId364025"></a><a name=
  "band_as_gff"></a>The featuretext option can also contain
  GFF</h3><a href="#GFF_data">GFF data</a> will also be parsed
  correctly from the featuretext data.&nbsp; The GFF can be
  included anywhere in the text, as long as it is preceded by a
  '##gff-version' directive.<br>
  <br>

  <h3><a class="mozTocH4" name="mozTocId586042"></a>Comments</h3>

  <p>You can place a comment in the annotation file by preceding it
  with a pound sign (#). Everything following the pound sign is
  ignored:</p>

  <blockquote>
    <pre>
# this is a comment<br>
<br>
</pre>
  </blockquote><br>
  <hr>

  <h1><a class="mozTocH2" name="mozTocId221012"></a><a name=
  "browser_config"></a> Browser customization and
  configuration</h1>

  <h2><a class="mozTocH3" name="mozTocId854590"></a><a name=
  "base"></a>The base configuration file</h2>This is an example of
  Gbrowse_karyotype.conf.&nbsp; It contains basic configuration
  information for drawing karyotypes when no server-side data
  source is used.&nbsp; This is formatting information only.&nbsp;
  All of the data needed to draw the chromosomes must be supplied
  via CGI parameters.&nbsp;<br>
  <br>
  <span style="font-weight: bold;">Note:</span> The base
  configuration is only used if no data source is specified and no
  style information is otherwise supplied.&nbsp; These values will
  be overidden by style information supplied as <a href="#CGI">CGI
  parameters</a> and/or specific <a href="#data_source">data source
  configuration files</a>.<br>
  <span style="font-weight: bold;">Note2:</span> for options that
  can be used either as <a href="#CGI">CGI parameters</a> or in
  configuration files, use the long form, rather than the short
  alias, in the confuguration file.<br>
  <br>
  # default configuration for gbrowse_karyotype<br>
  <pre style="background-color: gainsboro; width: 800px;">
[GENERAL]
description = no source

max segment = 999_999_999_999_999

# Web site configuration info
tmpimages   = /gbrowse/tmp
stylesheet  = /gbrowse/gbrowse.css
buttons     = /gbrowse/images/buttons

[karyotype]
cheight         = 500 # max chromosome height
cwidth          = 25  # chromosome width
cytoband_track  = ideogram
bands           = chromosome_band cytoband centromere
useform         = 1 # print a data entry form if there are no CGI parameters
##################################################################
# For a customized input form, the following options would be
# uncommented and filled with HTML code
##################################################################
# This option would contain HTML code for a customized page header
#header          =
# 
# This option would contain HTML code for a customized page footer
#footer          = 
#
# This option would contain HTML code for a customized input form
#input_form      = 
###################################################################


# Default glyph settings
[TRACK DEFAULTS]
glyph       = triangle
height      = 8
bgcolor     = black
fgcolor     = black
description = 0
label       = 0
orient      = E
point       = 1

[ideogram]
glyph       = ideogram
fgcolor     = black
<a href=
"#band_colors">bgcolor</a>  = gneg:white gpos25:silver gpos50:gray gpos:gray
              gpos75:darkgray gpos100:black gvar:var stalk:#666666
arcradius   = 7
height      = 20
bump        = 0
</pre><br>

  <h2><a class="mozTocH3" name="mozTocId730868"></a><a name=
  "data_source"></a>The data source configuration file<br></h2>
  <pre style="background-color: gainsboro; width: 800px;">
Example:
# This is a basic configuration to draw chromosome ideograms for the
# human genome.  It is a standalone file but could could also be part
# of a normal gbrowse configuration file. 
[GENERAL]
description   = human
db_adaptor    = Bio::DB::GFF
# this configuration just uses a simple flatfile
db_args       = -adaptor memory
                -gff    'usr/local/apache/htdocs/gbrowse/databases/ideograms/human_cytobands.gff'

# Where temporary images are stored
tmpimages   = /gbrowse/tmp

# gbrowse_karyotype-specific configuration
[karyotype]
max_height       = 400
cwidth           = 15
chromosome       = 1 2 3 4 5 6 7 8 9 10 11 12 13
                   14 15 16 17 18 19 20 21 22 X Y
rows             = auto
cytoband_track   = CYT:karyotype
band_labels      = 1

# this controls how the chromosomes are drawn
[CYT:karyotype]
feature       = cytoband chromosome_band centromere
glyph         = ideogram
fgcolor       = black
bgcolor       = gneg:white gpos25:silver gpos50:gray gpos:gray
                gpos75:darkgray gpos100:black gvar:var stalk:#666666
arcradius     = 7
height        = 21

# Other built-in feature configuration, if any,  would be added here
</pre>

  <p><br></p>

  <h2><a class="mozTocH3" name="mozTocId66137"></a><a name=
  "interactive"></a>gbrowse_karyotype as an interactive
  browser</h2>

  <p>The CGI script can be used as an interactive browser using the
  <span style="font-style: italic;">useform=1</span>
  option.<br></p>

  <p>In the configuration file, a customized data entry form can be
  specified using the following options:</p>

  <ul>
    <li>The front page for the interactive browser can be almost
    entirely customized with the following keys in the [karyotype]
    stanza.

      <ul>
        <li>
          <pre>
 header     = ... 
</pre>Page header biolerplate (Visible title, etc.)
        </li>

        <li>
          <pre>
 input_form = ... 
</pre>HTML to replace eveything between the header and footer
        </li>

        <li>
          <pre>
 footer     = ... 
</pre>Page footer
        </li>
      </ul>

      <p>If the useform option is specified in the configuration
      file but the above fields are not; reasonable, albeit plain,
      defaults will be supplied by the CGI script.</p>
    </li>
  </ul>&nbsp;&nbsp;&nbsp;
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span style="font-style: italic;">&nbsp;
  This if the default data entry form</span><br>
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <iframe src=
  "/cgi-bin/gbrowse_karyotype?useform=1" height="700" width=
  "700"></iframe><br>
  <br>
  <br>

  <ul>
    <li>
      <pre>
chromosome = chr1 chr2 chr3
</pre>This entry is required to specify which chromosomes to
display and in which order. The space delimited list should contain
reference sequences that exist in your database or GFF flat file.
    </li>

    <li>
      <pre>
cytoband = CYT:karyotype
</pre>This specifies which built-in feature corresponds to the
chromosome band data. If there are no band data, blank chromosomes
will be drawn. However, a configuration stanza is still necessary
to specify default chromosome attributes.
    </li>

    <li>
      <pre>
feature = cytoband chromosome_band centromere</pre>
          List individual feature types (typically chromosome_band
          and centromere).  'cytoband' is also recognized but it is not
          a valid SO term.  List actual features, not aggregators.
    </li>

    <li>
      <pre>
glyph  = ideogram
</pre>
         The ideogram glyph would be most commonly used in combination
         with cytoband data.  An alternative for scored, non cytoband
         features (for example local gene densites, recombination rates,
         etc) is the heat_map_ideogram glyph, which can be used to draw
         chromosomes with color-coded bands representing scores, frequencies
         etc. The chromosome-like look can be enhanced by including
         the centromere amongst the scored "bands".
  
    </li>
  </ul>
  <pre>
<br>
</pre>

  <h1><a class="mozTocH2" name="mozTocId329627"></a><a name=
  "cytoband"></a>How to obtain and use cytoband data</h1>

  <p>The starting point for drawing chromosome ideograms is the
  cytoband data. These data can be obtained from the UCSC genome
  browser, from NCBI and from EnsEMBL and other sources such as the
  primary literature. Once obtained, the cytobands are converted to
  GFF to be loaded into a Bio::DB::GFF database or saved as a
  flatfile.</p>

  <p>Below is an example of GFF3-format cytoband data. Note that
  the Parent= tag is used to facilitate aggregation of bands into
  their parent chromosomes. Preprocessed GFF files for mouse, human
  and rat can be found in the html (or htdocs) directory at
  gbrowse/databases/ideogram.<br></p>

  <h2><a class="mozTocH2" name="mozTocId384003"></a>Format and
  graphical rendering of chromosome bands</h2>The CGI/config
  options that specifically control how chromosomes are drawn for
  configured data sources are shown below:<br>
  <br>
  <pre style="background-color: gainsboro; width: 800px;">
[karyotype]
# This option tells the CGI script which features to interpret as
# "cytoband" features to be drawn on the chromosome ideograms.  
# The three feature types below are assumed by default but
# Other types can be used as well.
bands          = chromosome_band centromere cytoband
# This is where the names and order of the chromosomes are specified
chomosome      = 1 2 3 4 5 6
# This option specifies that band labels should be added
band_labels    = 1
# This option species the configuration section that applies to the chromosome ideograms
cytoband_track = ideogram
# Largest chromosome height
cheight        = 500

# This section provides default style options
# for the chromosomes.  Note the specially formatted bgcolor (see below)
[ideogram]
glyph       = ideogram
fgcolor     = black
bgcolor     = gneg:white gpos25:silver gpos50:gray gpos:gray gpos75:darkgray 
              gpos100:black gvar:var stalk:#666666
arcradius   = 7
height      = 20
bump        = 0
</pre>

  <h3><a class="mozTocH3" name="mozTocId609743"></a>Stains and
  background colors<br></h3>The specially formatted bgcolor option
  is parsed to control band colors individually for each cytoband
  feature other than the centromere.<br>
  each 'stain:color' pair specifies the color to draw each band
  feature, each of which has a 'stain' attribute associated with
  it.<br>
  The stains can be anything, with the exceptions noted below:<br>
  <br>

  <h3><a class="mozTocH3" name="mozTocId691394"></a>Tips, stalks,
  and centromeres</h3>The keyword '<span style=
  "font-weight: bold;">tip</span>' refers to the very top of&nbsp;
  mouse chromosomes, which are extremely acrocentric.&nbsp; This
  stain will cause a small, black, rectangular chromosome tip.<br>
  The keyword '<span style="font-weight: bold;">stalk</span>' will
  cause a narrower band that represents the stalk region of human
  acrocentric chromosomes.<br>
  Centromeres are usually specified by type, but the keyword
  '<span style="font-weight: bold;">acen</span>' will also cause a
  band to be rendred as a centromere.<br>
  The keyword '<span style="font-weight: bold;">gvar</span>' will
  create a band that has a patterned background color.<br>
  <br>
  <br>

  <h2><a class="mozTocH3" name="mozTocId235550"></a><a name=
  "GFF_data"></a>Sample GFF data<br></h2>
  <pre style="background-color: gainsboro;">
  ##gff-version 3
  ##sequence-region 1 1 245522847
  1       ensembl chromosome_band        1       2300000 .       .       .       Parent=1;Name=p36.33;Alias=1p36.33;Stain=gneg
  1       ensembl chromosome_band        2300001 5300000 .       .       .       Parent=1;Name=p36.32;Alias=1p36.32;Stain=gpos25
  1       ensembl chromosome_band        15600001        20200000        .       .       .       Parent=1;Name=p36.13;Alias=1p36.13;Stain=gneg
  1       ensembl centromere      121000001       127900000       .       .       .       Parent=1;Name=1_cent;Alias=11_cent
</pre><span style="font-weight: bold;">Note:</span> If a GFF
flatfile is being used as the database for chromosome banding data,
be sure to have a 'sequence-region' directive for each
chromosome.<br>
  <br>

  <h2><a class="mozTocH3" name="mozTocId323980"></a>Sample Data
  Extraction script</h2>

  <p>Ensembl has cytoband data for human, mouse and rat. Below is
  an example of a script that retrieves cytoband features from the
  public mysql database and converts them to GFF3.</p><br>
  <pre style="background-color: gainsboro; width: 800px;">
#!/usr/bin/perl -w
use strict;
use DBI;

my $database = shift;
my $host     = 'ensembldb.ensembl.org';
my $query    = 
'SELECT name,seq_region_start,seq_region_end,band,stain
 FROM seq_region,karyotype
 WHERE seq_region.seq_region_id = karyotype.seq_region_id;';


my $dbh = DBI-&gt;connect( "dbi:mysql:$database:$host", 'anonymous' )
    or die DBI-&gt;errstr;

my $sth = $dbh-&gt;prepare($query) or die $dbh-&gt;errstr;
$sth-&gt;execute or die $sth-&gt;errstr;

my ($cent_start,$prev_chr,$chr_end,$segments,$gff);
my $chr_start = 1;
while (my @band = $sth-&gt;fetchrow_array ) {
  my ($chr,$start,$end,$band,$stain) = @band;
  my $class = 'Chromosome';
  my $method;

  $chr =~ s/chr//;
  if ($stain eq 'acen' &amp;&amp; !$cent_start) {
    $cent_start = $start;
    next;
  }
  elsif ($cent_start) {
    $method = 'centromere';
    $band   = "$chr\_cent";
    $start  = $cent_start;
    $stain  = '';
    $cent_start = 0;
  }
  else {
    $method = 'chromosome_band'; # SO term
  }

  my $alias = $method =~ /centromere/i ? $band : $chr.$band;
  $gff .= join("\t", $chr, 'ensembl', lc $method, $start, $end,
         qw/. . ./,qq{Parent=$chr;Name=$band;Alias=$alias});
  $gff .= $stain ? ";Stain=$stain\n" : "\n";

  if ($prev_chr &amp;&amp; $prev_chr !~ /$chr/) {
    $segments .= "\#\#sequence-region $prev_chr $chr_start $chr_end\n";
    $chr_start = 1;
  }

  $prev_chr = $chr;
  $chr_end  = $end;
}

$segments .= "\#\#sequence-region $prev_chr $chr_start $chr_end\n";
print "##gff-version 3\n";
print $segments,$gff;

__END__
# Currently ideograms for human, rat and mouse are available
# To see the current database list, try the command:

mysql -uanonymous -hensembldb.ensembl.org -e 'show databases' \ 
| grep core | grep 'sapiens\|rattus\|mus' | grep -v 'expression'
</pre><br>

  <h2><a class="mozTocH2" name="mozTocId133625"></a>Options for
  server-side storage of chromosome band data</h2>

  <h3><a class="mozTocH3" name="mozTocId231053"></a>In a relational
  database</h3>Cytoband data can be stored in a Bio::DB::GFF
  database just like any other, properly formatted GFF.&nbsp; See
  the <a href="/gbrowse/tutorial/tutorial.html">Gbrowse
  tutorial</a> for more information on database loading and
  configuration.<br>
  Below is an example of hoe the database access would be specified
  in the data source config file:<br>
  <br>
  <pre style="background-color: gainsboro; width: 800px;">
db_adaptor    = Bio::DB::GFF
db_args       = -dsn dbi:mysql:database=my_database;host=localhost;user=user;password=passwd
</pre><br>

  <h3><a class="mozTocH3" name="mozTocId362510"></a>As a flat
  file</h3>Cytoband data, such as the output of the above example
  script, can be stored as a GFF file on the webserver's filesystem
  and parsed into memory at runtime.<br>
  A sample configuration is shown below:<br>
  <br>
  <pre style="background-color: gainsboro; width: 800px;">
db_adaptor    = Bio::DB::GFF
db_args       = -adaptor memory
                -gff '/var/www/html/gbrowse/databases/ideograms/mouse_cytobands.gff'
</pre>Ensure that the GFF data in the flatfile is formatted as the<br>
<a href="#GFF_data">above sample</a>.
  <br>

  <h1><a class="mozTocH1" name="mozTocId311487"></a>Other usage
  examples:</h1>

  <h2><a class="mozTocH2" name="mozTocId745944"></a>Using
  non-standard cytoband features: Human gene density
  plot<br></h2>The image below is drawn using a Bio::DB::GFF
  database that specifies gene_density features rather than
  chromosome_bands.&nbsp; Each gene_density feature (see sample
  GFF) has a score, which corresponds to the number of genes
  /megabase.&nbsp;<br>
  <br>

  <h3><a class="mozTocH3" name="mozTocId749659"></a>Sample GFF
  data</h3>
  <pre style="background-color: gainsboro;">
##gff-version 3
1       calculated      gene_density    1       1000000 35      .       .       Parent=Dense:1
1       calculated      gene_density    1000001 2000000 45      .       .       Parent=Dense:1
1       calculated      gene_density    2000001 3000000 18      .       .       Parent=Dense:1
1       calculated      gene_density    3000001 4000000 21      .       .       Parent=Dense:1
1       calculated      gene_density    4000001 5000000 1       .       .       Parent=Dense:1
1       calculated      gene_density    5000001 6000000 1       .       .       Parent=Dense:1
1       calculated      gene_density    6000001 7000000 21      .       .       Parent=Dense:1
1       calculated      gene_density    7000001 8000000 12      .       .       Parent=Dense:1
1       calculated      gene_density    8000001 9000000 18      .       .       Parent=Dense:1
1       calculated      gene_density    9000001 10000000        20      .       .       Parent=Dense:1
1       calculated      gene_density    10000001        11000000        18      .       .       Parent=Dense:1
1       calculated      gene_density    11000001        12000000        28      .       .       Parent=Dense:1
1       calculated      gene_density    12000001        13000000        25      .       .       Parent=Dense:1
1       calculated      gene_density    13000001        14000000        10      .       .       Parent=Dense:1
1       calculated      gene_density    14000001        15000000        3       .       .       Parent=Dense:1
1       calculated      gene_density    15000001        16000000        27      .       .       Parent=Dense:1
1       calculated      gene_density    16000001        17000000        45      .       .       Parent=Dense:1
1       calculated      gene_density    17000001        18000000        15      .       .       Parent=Dense:1
1       calculated      gene_density    18000001        19000000        6       .       .       Parent=Dense:1
1       calculated      gene_density    19000001        20000000        23      .       .       Parent=Dense:1
1       calculated      gene_density    20000001        21000000        20      .       .       Parent=Dense:1
1       calculated      gene_density    21000001        22000000        14      .       .       Parent=Dense:1
1       calculated      gene_density    22000001        23000000        17      .       .       Parent=Dense:1
1       calculated      gene_density    23000001        24000000        27      .       .       Parent=Dense:1
</pre>

  <h3><a class="mozTocH3" name="mozTocId225713"></a>Configuration
  file</h3>The file Human_gene_density.conf contains the following
  text. This configuration uses the heat_map_ideogram glyph, which
  is like the ideogram glyph but allows bands to have their color
  calculated based on the score (see GFF above).
  <pre style="width: 600px; background-color: gainsboro;">
description   = Human gene density
db_adaptor    = Bio::DB::GFF
db_args       = -dsn dbi:mysql:database=human;host=localhost;user=nobody

# Web site configuration info
tmpimages   = /gbrowse/tmp
stylesheet  = /gbrowse/gbrowse.css
buttons     = /gbrowse/images/buttons

# how long to save cached images
image cachetime = 2_592_000

[karyotype]
cheight         = 500
cwidth          = 20
chromosome      = 1 2 3 4 5 6 7 8 9 10 11 12 13
                  14 15 16 17 18 19 20 21 22 X Y
cytoband_track  = CYT

[CYT]
feature       = gene_density centromere
glyph         = heat_map_ideogram # note the different glyph
start_color   = white
end_color     = red
min_score     = 0
max_score     = 40
fgcolor       = black
</pre>

  <h3><a class="mozTocH3" name="mozTocId271427"></a>URL</h3>Since
  the configuration and data are on the web server, a very simple
  url is required:<br>
  &nbsp;
  "http://mckay.cshl.edu/cgi-bin/gbrowse_karyotype/Human_gene_density"<br>

  <br>
  <img alt="human gene density plot" title=
  "human gene density plot" src="/gbrowse/gene_density.png" style=
  "width: 768px; height: 530px;"><br>
  <br>
  <br>

  <h2><a class="mozTocH2" name="mozTocId764480"></a>Loading
  chromosome band data remotely<br></h2>It is also possible to draw
  a whole genome "from scratch" with no server-side data.&nbsp;
  Chromosome and band data and configuration passed as CGI
  arguments at runtime.&nbsp;<br>
  The following arguments apply (<span style=
  "font-weight: bold;">chromosome</span> is the only required
  option):<br>
  <br>

  <h3><a class="mozTocH3" name="mozTocId360354"></a>CGI
  arguments<br></h3><br>
  &nbsp;&nbsp;&nbsp; bands=feature_type1+feature_type2*<br>
  &nbsp;&nbsp;&nbsp; chromosome=1:10000000+2:500000 etc (see
  <a href="#chromosome">above</a> for more details)<br>
  &nbsp;&nbsp;&nbsp;
  add=1+chromosome_band+1p23+1..10000000+Stain=gpos50 etc.<br>
  <br>
  <small><sup>*</sup>This is only required if features other than
  the default 'chromosome_band', 'cytoband' and 'centromere' are
  used.<br>
  <sup>+</sup>Cytoband data are not required.&nbsp; Blank
  chromosomes will be drawn in their absence</small>.<br>
  <br>
  The chromosome band data can be passed the same way as any other
  type of feature, via the <a href="#add">add</a> or <a href=
  "#featuretext">featuretext</a> options.&nbsp;<br>
  <br>

  <h3><a class="mozTocH3" name="mozTocId499814"></a>GET vs. POST
  method<br></h3>If there large numbers of chromosome bands and/or
  other annotations to be drawn, a very long URL submitted via the
  GET method may become unwieldy.&nbsp; Consider submitting a form
  using the featuretext option and the POST method.&nbsp; If you
  already have the chromosome band data in GFF format, it can
  simply be <a href="#bands_as_GFF">appended to the other
  featuretext data</a>.&nbsp; If each of the chromosomes is
  specified as a sequence-region directive in the GFF data, then
  the otherwise requisite 'chromosome' option is not required.<br>
  <br>
  &nbsp;&nbsp;<br>
  <pre>
##sequence-region chromosome_name start end
</pre><br>
  The HTML code shown below embeds a complete human chromosome 21
  with superimposed features within a web page:<br>
  <br>
  <pre style="background-color: gainsboro;">
   &lt;form method=POST name="f1" action="/cgi-bin/gbrowse_karyotype_devel" target="iframe1"&gt;
    &lt;input type="hidden" name="embed" value=1&gt;
    &lt;input type="hidden" name="band_labels" value=1&gt;
    &lt;input type=submit name="submit" value="Click to display chromosome 21"&gt;
    &lt;!-- The textarea is not visible --&gt;
    &lt;div style="width:0px;height:0px;visibility:hidden"&gt;
    &lt;textarea name="featuretext" type=hidden&gt;
     ## Configuration
     [gene]
     glyph   = triangle
     bgcolor = red
     fgcolor = red
     height  = 7
     bump    = 1
     point   = 1

     [mutation]
     glyph   = lightning
     bgcolor = yellow
     fgcolor = black
     height  = 15

     # chromosome 1
     reference=21
     gene gene1 20000001..20006000 "Some sort of gene"
     gene gene2 30066001..30069000 bgcolor=white;desc="ADH gene"
     gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene"
     gene gene6 40000001..40006000 glyph=dot;bgcolor=white;fgcolor=black;height=15
     mutation allele2 30006001..30009000 link=http://www.nasa.gov;description="cosmic radiation damage"


     # chromosome 21 cytoband data
     ##gff-version 3
     ##sequence-region 21 1 46944323
     21      ensembl chromosome_band 1       2900000 .       .       .       Parent=21;Name=p13;Alias=21p13;Stain=gvar
     21      ensembl chromosome_band 2900001 6300000 .       .       .       Parent=21;Name=p12;Alias=21p12;Stain=stalk
     21      ensembl chromosome_band 6300001 10000000        .       .       .       Parent=21;Name=p11.2;Alias=21p11.2;Stain=gvar
     21      ensembl chromosome_band 13200001        15300000        .       .       .       Parent=21;Name=q11.2;Alias=21q11.2;Stain=gneg
     21      ensembl chromosome_band 15300001        22900000        .       .       .       Parent=21;Name=q21.1;Alias=21q21.1;Stain=gpos100
     21      ensembl chromosome_band 22900001        25800000        .       .       .       Parent=21;Name=q21.2;Alias=21q21.2;Stain=gneg
     21      ensembl chromosome_band 25800001        30500000        .       .       .       Parent=21;Name=q21.3;Alias=21q21.3;Stain=gpos75
     21      ensembl chromosome_band 30500001        34700000        .       .       .       Parent=21;Name=q22.11;Alias=21q22.11;Stain=gneg
     21      ensembl chromosome_band 34700001        36700000        .       .       .       Parent=21;Name=q22.12;Alias=21q22.12;Stain=gpos50
     21      ensembl chromosome_band 36700001        38600000        .       .       .       Parent=21;Name=q22.13;Alias=21q22.13;Stain=gneg
     21      ensembl chromosome_band 38600001        41400000        .       .       .       Parent=21;Name=q22.2;Alias=21q22.2;Stain=gpos50
     21      ensembl chromosome_band 41400001        46944323        .       .       .       Parent=21;Name=q22.3;Alias=21q22.3;Stain=gneg
     21      ensembl centromere      10000001        13200000        .       .       .       Parent=21;Name=21_cent;Alias=21_cent
    &lt;/textarea&gt;
   &lt;/div&gt;
  &lt;/form&gt;

  &lt;!-- The iframe where the image and map will be embedded --&gt;
  &lt;iframe name="iframe1" id="iframe1" height=600 frameborder=0&gt;&lt;/iframe&gt;
</pre><br>
  <!-- The actual code -->

  <form method="post" name="f1" action=
  "/cgi-bin/gbrowse_karyotype_devel" target="iframe1">
    <input type="hidden" name="embed" value="1"> <input type=
    "hidden" name="band_labels" value="1"> <input type="submit"
    name="submit" value="Click to display chromosome 21"> 
    <!-- The textarea is not visible -->

    <div style="width:0px;height:0px;visibility:hidden">
      <textarea name="featuretext" type="hidden">
## Configuration
     [gene]
     glyph   = triangle
     bgcolor = red
     fgcolor = red
     height  = 7
     bump    = 1
     point   = 1

     [mutation]
     glyph   = lightning
     bgcolor = yellow
     fgcolor = black
     height  = 15

     # chromosome 1
     reference=21
     gene gene1 20000001..20006000 "Some sort of gene"
     gene gene2 30066001..30069000 bgcolor=white;desc="ADH gene"
     gene gene3 50000001..50006000 bgcolor=blue;fgcolor=blue;glyph=dot;description="Unknown gene"
     gene gene6 40000001..40006000 glyph=dot;bgcolor=white;fgcolor=black;height=15
     mutation allele2 30006001..30009000 link=http://www.nasa.gov;description="cosmic radiation damage"


     # chromosome 21 cytoband data
     ##gff-version 3
     ##sequence-region 21 1 46944323
     21      ensembl chromosome_band 1       2900000 .       .       .       Parent=21;Name=p13;Alias=21p13;Stain=gvar
     21      ensembl chromosome_band 2900001 6300000 .       .       .       Parent=21;Name=p12;Alias=21p12;Stain=stalk
     21      ensembl chromosome_band 6300001 10000000        .       .       .       Parent=21;Name=p11.2;Alias=21p11.2;Stain=gvar
     21      ensembl chromosome_band 13200001        15300000        .       .       .       Parent=21;Name=q11.2;Alias=21q11.2;Stain=gneg
     21      ensembl chromosome_band 15300001        22900000        .       .       .       Parent=21;Name=q21.1;Alias=21q21.1;Stain=gpos100
     21      ensembl chromosome_band 22900001        25800000        .       .       .       Parent=21;Name=q21.2;Alias=21q21.2;Stain=gneg
     21      ensembl chromosome_band 25800001        30500000        .       .       .       Parent=21;Name=q21.3;Alias=21q21.3;Stain=gpos75
     21      ensembl chromosome_band 30500001        34700000        .       .       .       Parent=21;Name=q22.11;Alias=21q22.11;Stain=gneg
     21      ensembl chromosome_band 34700001        36700000        .       .       .       Parent=21;Name=q22.12;Alias=21q22.12;Stain=gpos50
     21      ensembl chromosome_band 36700001        38600000        .       .       .       Parent=21;Name=q22.13;Alias=21q22.13;Stain=gneg
     21      ensembl chromosome_band 38600001        41400000        .       .       .       Parent=21;Name=q22.2;Alias=21q22.2;Stain=gpos50
     21      ensembl chromosome_band 41400001        46944323        .       .       .       Parent=21;Name=q22.3;Alias=21q22.3;Stain=gneg
     21      ensembl centromere      10000001        13200000        .       .       .       Parent=21;Name=21_cent;Alias=21_cent
   
</textarea>
    </div>
  </form>
  <!-- The iframe where the image and map will be embedded -->
  <iframe name="iframe1" id="iframe1" height="600" frameborder=
  "0"></iframe><br>

  <h1><a class="mozTocH2" name="mozTocId244872"></a>SEE
  ALSO:<br></h1><a href="/gbrowse/tutorial/tutorial.html">The
  gbrowse tutorial</a><br>
  perldoc Bio::Graphics::Glyph::ideogram<br>
  <br>

  <h1><a class="mozTocH2" name="mozTocId812098"></a>BUGS</h1>

  <p>Please report them to the author.<br></p>

  <h1><a class="mozTocH2" name="mozTocId27339"></a>AUTHOR</h1>

  <p>Sheldon McKay&nbsp;&nbsp; <a href=
  "mailto:mckays%5C@cshl.edu">mckays@cshl.edu</a></p>

  <p>Copyright (c) 2006 Cold Spring Harbor Laboratory</p>

  <p>This program is free software; you can redistribute it and/or
  modify it under the same terms as Perl itself.</p>

  <p>For additional help, see <a href="http://www.gmod.org">The
  GMOD Project</a> pages.</p>
</body>
</html>
